HLPBMP.TXT - Helpful Hints for BMP placement into WinHelp RTF/HLP files 4/12/92 This long-winded text file explains some reported problems with importing and placing bitmapped images into Rich Text Format (RTF) files, and addresses problems associated with compiling those RTF files into Windows Help (HLP) files via the Microsoft Help Compiler (HC.EXE). It won't improve your sex life, or get rid of morning breath, but it might make it easier to plop graphics into your Windows Help files... BACKGROUND ---------- "Wouldn't it be great if it was easier to add graphics to your Windows Help files...?" "Wouldn't it be great if the Help Compiler didn't always toss out my RTF files with an error message...?" Well, sure it would -- on both counts. Lots of fellow TPW users routinely report difficulties importing bitmaps into the RTF files they plan to compile into Windows Help files. Most of these folks use graphical word processors and feel cheated when they drop graphic images into their RTF text with the Windows Clipboard, only to see the resulting RTF file die a horrible death at compile time... A quick glance through the message threads in the Windows SDK forum indicates that we are not alone; these same complaints are cropping up from Windows programmers working in a variety of development platforms. For TPW users, the following scenario is fairly common: We're following the instructions laid out in the Turbo Pascal for Windows HELP COMPILER booklet, we're using a bona-fide graphical word processor (commonly Microsoft Word for Windows) for handling the RTF file and graphics importing/positioning, and we're attempting to compile our HLP file with the version of HC.EXE that came bundled with TPW... ...and we're still getting the same old "Unrecognized Graphic Format..." error message at compile time, despite the fact that we're following each and every one of the HELP COMPILER instructions to the LETTER. JUST THE FACTS, MA'AM... ------------------------ In the way of a solution, there are a few things that we know at the outset that might or might not help some of you. First off, there has been much made of the limitation on clipboard- placed bitmap image size that Word for Windows and/or the Help Compiler imposes. In addition, more than a few postings in the Windows SDK forum mention something about a 64 Kb "paragraph size" ceiling in Word for Windows. One chap in the SDK forum even claimed that he knew one (and only one) person who used Word for Windows to successfully drop a bitmap image into an RTF file via the Clipboard "Copy" and "Paste" commands -- and (mirabile dictu!) the RTF file compiled cleanly into a HLP file. He went on to explain (reverently) that this astounding feat was only possible because the bitmap in question was "very small" and had been generated using the SDK paint editor! Oooof! No mention was made of incense burning, animal sacrifice, or the chanting of mantras. And the bogey-man was not available for comment. While much of what you've heard or read on the various Windows programming forums might be true, it really has precious little bearing on what Microsoft's Help Compiler is actually able to "swallow" during HLP file compilation. For the most part, warnings about bitmap image size or WinWord "paragraph size" seem to be lame attempts at explaining away the recurring compiler error messages. In fact, I've been able to successfully import and position clipboard-placed COLOR bitmapped images as large as 210x80 pixels with absolutely no problem. The RTF files containing these images were then compiled into HLP files with nary a hiccup. Ran just fine from WinHelp. No problemo. These are just examples, mind you. Certainly, there exists the potential to make use of even larger images, especially if they are monochrome bitmaps. From an aesthetic point of view, however, there is some question of whether you would really WANT to do this. Past a certain point, oversized (or overused) graphics can actually DETRACT from the effectiveness of your Help System file. Where that particular point lies for you is YOUR CHOICE, and none of my business anyway. THE COMPILER ------------ Okay, now to the meat and potatoes. First, it might help to establish which version of HC.EXE you have. The version that came bundled with TPW when I purchased it is version 3.0. That might or might not be what most of you are using right now. I'm not going to come right out and say that version 3.0 won't do the job, because deep down I feel that it does. What I WILL say is that version 3.0b is alleged to be "friendlier" as far as RTF files generated with Microsoft Word for Windows (this, according to posts and message threads on the CompuServe Windows SDK forum). True? False? Who cares? 3.0b works for me, so I'm not complaining. HC.EXE 3.0b is currently available on the Windows SDK forum. The file size is 133,835 Kb, and it isn't compressed (!) so your download might take quite a while. Note: There are rumors circulating that version HC.EXE 3.1 is on the way. When and if it becomes available, my advise is to snatch it up. THE WORD PROCESSOR ------------------ There are a few excellent shareware utilities out there that convert ASCII text files to RTF format, allowing the user to avoid having to mess with "expensive" and "complicated" graphical word processors like Word for Windows. My HUNCH is that many of the people who use these utilities actually already have a Windows word processor that supports RTF formats, already know how to use it, but just can't get the damned thing to import bitmaps into an RTF file that HC.EXE can compile cleanly. I know that's the category into which I fell. So, what's this to YOU? Well, let's look at the choices available to folks looking to put graphics into their help files. According to the HELP COMPILER manual, we have exactly TWO: 1) You can place the image on the "page" BY REFERENCE (i.e., by entering formatting code that tells the compiler where to put the BMP file image. This will work, but it's not as easy or as flexible as plopping the image in via the Windows Clipboard. In addition, this method requires the inclusion of a [BITMAPS] section in your HPJ file; the compiler will need you to keep careful track of each bitmap used in the help file. For people using a text-only word processor, this is the only method available -- but if you're programming for Windows, doesn't that hint that you prefer doing things GRAPHICALLY...? -or- 2) You can place it on the "page" GRAPHICALLY (i.e., copying and pasting the image via the Windows Clipboard). In a perfect world, this would be the quickest, easiest, fuss-free method. The problem is, the world isn't perfect. Where clipboard-placed images are concerned, there's more than one way to skin the proverbial cat, and (in my experience) HC.EXE only accepts ONE of those methods. ASSUMPTIONS ----------- The following instructions make two assumptions about the programs you're using: A) You have HC.EXE (3.0b). B) You have Word for Windows (2.0) If you have both of the above programs, but not the most recent version, these instructions might still work. I just don't want to make any false promises. If you have a different Windows word processor (WordPerfect for Windows, Ami Pro, etc.) you're not entirely out of luck. In fact, during a late-night romp through the Windows SDK forum, I ran across WPWINH.ZIP -- a useful WordPerfect for Windows macro/resource that addresses and corrects some problems that WPWin seems to have with RTF files. WPWINH.ZIP even includes a custom button bar addition that allows the user to open RTF files with one click of the mouse. If you're a WordPerfect for Windows user like me, it's definitely worth a look-see. PROCEDURES ---------- 1) For starters, the bitmap image(s) should be in Windows BMP format (color or B/W). It doesn't much matter what paint program you use to create the bitmap (some folks use Windows PaintBrush, some like WRT's paint editor, some prefer the paint editor in Borland's Resource Toolkit). Caveats: a) It is a great advantage if your image is prepared in the same dimensions you'll want it displayed. The whole process seems to smile on imported images that don't required size scaling. b) That said, it IS generally better to shy away from overly large bitmaps -- not because of memory or compiler considerations, but because large bitmaps can be obtrusive (and distracting) in the Windows Help system. 2) Run Microsoft Word for Windows. a) Open a blank document file in one window (DOCUMENT1 -- this usually happens automatically). b) Open the target RTF file in a second window. c) Move to the blank file edit screen (DOCUMENT1). 3) From the menu bar, select "Insert/Picture." From the dialog box that follows, select the desired BMP file (you may have to "browse" a bit to track it down). a) Word will respond by creating an empty "frame" on the edit screen, representing the position of the imported bitmap image. b) Don't panic if the graphic area is "empty" (you can always reassure yourself that the image is "really there" by toggling to the menu bar "File/Print Preview"). In fact, an "empty" graphic is actually a good sign (more on this later). 4) With the mouse pointer, highlight the graphic area. Select the menu bar "Edit/Copy" command to copy it to the Windows Clipboard. 5) Move to the window containing the RTF file. Locate the cursor at the position you wish to insert the bitmap image, then select the menu bar "Edit/Paste" command. The image frame will appear on the edit screen, representing the position of the imported clipboard image. Note: This frame may be justified left, center, or right with the menu bar "Format" commands or via the button bar. Once imported, the same image may be copied and pasted several times within the RTF file without significantly increasing the file's size. Warning: The less you do with the image at this point, the better. Scaling and resizing can lead to unpredictable (i.e., BAD) results once the RTF file is compiled. 6) Save the finished file using the "Save As" command, remembering to save it in Rich Text Format. 7) The file may now be compiled with HC.EXE. Note: If all bitmaps in your RTF are imported in this manner, you will not need a [BITMAPS] section in your HPJ file. EXPLANATION ----------- At first, it seems silly to open a blank document for holding the "initial" importing of the BMP image prior to copying and pasting the image into the target text file. But there is method in this madness, honest. I found that using the "Two Windows" method neatly circumvents the quirky way that Word for Windows sometimes handles clipboard-placed images. Part of the problems people have with direct importing of bitmaps into Word for Windows is that Word will often consider the graphic to represent a BMP FILE, rather than a clipboard image. In this respect, Word behaves a bit like page layout programs like Aldus PageMaker handle imported graphics. When this happens, the file will LOOK great on the screen, because the image itself is actually visible during text editing. Unfortunately, this is really just a sign of trouble to come, since the resulting RTF file will likely generate an error message at compile time. By using the blank document as a "waypoint" for the bitmap, it becomes a little easier to transfer the image in true "clipboard" format to the waiting help text file. Why? Beats me. Some things man was not meant to know. In addition, though it is tempting to make use of Word's "Frame" feature for sliding a graphical element around on the screen, I'd advise against it. Again, for some reason, placing the clipboard image into a dedicated FRAME sometimes leads to the same old "Unrecognized Graphic Format..." error message when the resulting RTF file is compiled -- which we've been working to avoid all along. I don't claim that this is the only solution to all the reported difficulties, or that it's even the best solution. Simply put, it's just the FIRST solution that actually WORKED for me. ADDENDUM AD NAUSEUM ------------------- If you hit on any quicker or easier alternatives, or have any workarounds that involve other Windows word processors, please post them on BPROGA. Your fellow programmers will thank you for it! And, if you want to yell at me... well, I suppose you can do that, too. Matthew T. Smith 70661,3235 ___________ Microsoft, Windows, and Word for Windows are registered trademarks of Microsoft Corp. PageMaker is a registered trademark of Aldus Corp. So there.